CDF Overview

Tip: For information on the current CDF version, enter the following at the IDL prompt:

HELP, 'cdf', /DLM

The Common Data Format (CDF) is a file format that facilitates the storage and retrieval of multi-dimensional scientific data. CDF is a product of the National Space Science Data Center (NSSDC).

IDL’s CDF routines all begin with the prefix “CDF_”.

Programming Model

Creating CDF Files

The following table lists the basic IDL commands needed to create a new CDF file:

CDF_CREATE	Call this procedure to begin creating a new file. CDF_CREATE contains a number of keywords which affect the internal format of the new CDF file.
CDF_VARCREATE	Define the variables to be used in the file.
CDF_ATTPUT	Optionally, use attributes to describe the data.
CDF_VARPUT	Write the appropriate data to the CDF file.
CDF_CLOSE	Close the file.

Reading CDF Files

The following table lists the basic commands needed to read data from a CDF file:

CDF_OPEN	Open an existing CDF file.
CDF_READCDF	Retrieve an IDL hash of a CDF file's basic information, global attributes, variable information, etc.
CDF_READVARIABLE	Retrieve an IDL hash of a specified CDF variable's basic information, attributes, and data.
CDF_INQUIRE	Call this function to find the general information about the contents of the CDF file.
CDF_CONTROL	Call this function to obtain further information about the CDF file.
CDF_VARINQ	Retrieve the names, types, sizes, and other information about the variables in the CDF file.
CDF_VARGET	Retrieve the variable values.
CDF_ATTINQ	Optionally, retrieve the names, scope, and other information about the CDF file's attributes.
CDF_ATTGET	Optionally, retrieve the attributes.
CDF_CLOSE	Close the file.

If the structure of the CDF file is already known, you do not need to call the inquiry routines—only CDF_OPEN, CDF_ATTGET, CDF_VARGET, and CDF_CLOSE are needed.

Type Conversion

Values are converted to the appropriate type before being written to a CDF file. For example, in this code snippet IDL converts the string “12” to a floating-point 12.0 before writing it:

varid=CDF_VARCREATE(fileid, 'VarName',['VARY','VARY'],$

DIM=[2,3+5],/CDF_FLOAT)

CDF_VARPUT, fileid, 'VarName', '12' ; Reference by variable ID

Code Examples

Creating a CDF File

The following example demonstrates the basic procedure for creating a CDF file.

id = CDF_CREATE('Temperature.cdf', [2,3], /CLOBBER )

att_id = CDF_ATTCREATE(id, 'Title', /GLOBAL)

CDF_ATTPUT, id, att_id, 0, 'My Fancy CDF'

att1_id = CDF_ATTCREATE(id, 'Planet', /GLOBAL)

CDF_ATTPUT, id, 'Planet', 0, 'Mars'

time_id = CDF_VARCREATE(id, 'Time', ['NOVARY', 'NOVARY'], $

/REC_VARY)

att2_id = CDF_ATTCREATE(id, 'Time Standard', /VARIABLE_SCOPE)

; times are every half hour starting a 8 am GMT.

CDF_ATTPUT, id, att2_id, time_id, 'GMT'

FOR I=0,9 DO CDF_VARPUT, id, time_id, 8.+ 0.5 * I, rec_start=I

temp_id = CDF_VARCREATE(id, 'Temp', ['VARY', 'VARY'], $

/REC_VARY, /ZVAR, DIMENSIONS=[2,3])

long_id = CDF_VARCREATE(id, 'Longitude', ['VARY', 'VARY'], $

/REC_NOVARY)

lat_id = CDF_VARCREATE(id, 'Latitude', ['VARY', 'VARY'], $

/REC_NOVARY)

; write 10 temperature records:

CDF_VARPUT, id, temp_id, FINDGEN(2, 3, 10), /ZVARIABLE

; create longitudes:

CDF_VARPUT, id, long_id, [[10.0, 12.0], [8.0, 6.0], [3.0, 2.0]]

; create latitudes:

CDF_VARPUT, id, lat_id, [[40.0, 42.0], [38.0, 34.0],[30.0, 31.0]]

CDF_CLOSE, id

Variables and Attributes

Information in a CDF file consists of attributes (metadata) and collections of data records (variables).

Variables

IDL can create CDF files representing any data that can be stored in a zero- to eight-dimensional array. CDF supports two distinct types of variables, rVariables and zVariables. For reasons of efficiency, CDF uses variances to indicate whether data is unique between records and dimensions. For example, consider a data set of simultaneous surface temperatures at a variety of locations, the IDL code for creating the CDF file is included at the end of this section. A variable representing “GMT time” will vary from record to record, but not dimension to dimension (since all data are taken simultaneously). On the other hand, a variable such as longitude may not vary from record to record, but will vary from dimension to dimension. Record variance is set using the REC_VARY and REC_NOVARY keywords to CDF_VARCREATE, while dimensional variance is set through the DimVary argument to CDF_VARCREATE. In both cases, the default is varying data.

rVariables

rVariables (or regular variables) are multidimensional arrays of values, each having the same dimensions. That is, all rVariables in a CDF must have the same number of dimensions and dimension sizes. In IDL, the rVariable dimension sizes are declared when the CDF file is first created with CDF_CREATE. In the example at the end of this section, all variables except time are rVariables.

zVariables

zVariables (The z doesn’t stand for anything—the CDF people just like the letter z) are multidimensional arrays of values of the same data type. zVariables can have different dimensionality from other zVariables and rVariables. In general, zVariables are much more flexible, and therefore easier to use, than rVariables.

Attributes

Attributes can contain auxiliary information about an entire CDF file (global scope attributes or gAttributes), or about particular CDF variables (variable scope attributes or rAttributes/zAttributes depending on variable type). CDF attributes can be scalar or vector in nature, and of any valid datatype. In the case of vector, or multiple entry, attributes the user must keep track of the entry numbers (in CDF terms these are the gEntry, rEntry, or zEntry numbers depending on attribute type). For example, every rVariable in a CDF file might have an rAttribute named “Date”. A vector zVariable might have a zAttribute named “Location” with values such as [“Melbourne Beach”, “Crowley”,...]. A global attribute “MODS” might be used to keep track of the modification history of a CDF file (see CDF_ATTPUT). Note however, that variables cannot have multiple attributes with the same names. In IDL, CDF attributes are created with CDF_ATTPUT and retrieved with CDF_ATTGET.

Specifying Attributes and Variables

Variables and attributes can be referred to either by name or by their ID numbers in most CDF routines. For example, in the CDF_VARCREATE command shown in the example Type Conversion, the following command would have been equivalent:

; Reference by variable ID:

CDF_VARCREATE, fileid, varid, '12'

CDF File Options

File Type

The SINGLE_FILE and MULTI_FILE keywords to CDF_CREATE allow CDFs to be written as either:

1. all data in a single file, or
2. a separate file for each variable, plus a master file for global information.

Data Encodings/Decodings

Keywords to CDF_CREATE allow files to be written in a variety of data encoding and decoding options. (For example, the /SUN_ENCODING keyword creates a file in the SUN native encoding scheme). The default encoding/decoding is network (XDR). All CDF encodings and decodings can be written or read on all platforms, but matching the encoding with the architecture used provides the best performance. If you work in a single-platform environment most of the time, select HOST_ENCODING for maximum performance. If you know that the CDF file will be transported to a computer using another architecture, specify the encoding for the target architecture or specify NETWORK_ENCODING (the default). Specifying the target architecture provides maximum performance on that architecture; specifying NETWORK_ENCODING provides maximum flexibility.